Description
This manual connection member function requests 'update' access to the connected store. If there is an uncontended buffer available then it is claimed and its address returned. If there are no buffers available (they are all currently opened), then the call will block in accordance with the specified timeout, and then return TRUE if one becomes available within the timeout constraint; or FALSE if it does not. Before reading this topic, we would recommend familiarity with Manual Connections and Arbitrated Stores.
Prototype
Uns OpenUpdate( Int key,
Uns rule,
Uns timeout );
Parameters
key
This parameter can be used as a means of filtering reads and updates. If a writer and/or updater specifies a key in a construct call (see Store Records), then it is associated with the buffer instance. Readers and/or updaters that specify a key and a rule will only be granted access to data that satisfies their specified constraint. See Store Keys and Rules.
rule
This parameter can be used by readers and updaters as a means of filtering out data of interest (see Store Keys and Rules).
timeout
This parameter determines whether the connection will poll or block (see Connection Timeout). In this case it can only be set to poll (CLP_POLL) or block (CLP_WAIT). Millisecond timeouts are not supported. Since arbitrated stores are only usually held open for short periods this attribute is usually set to block.
Return Value
This function returns logical TRUE if the store is successfully opened for update within the timeout period; or FALSE otherwise.
Notes
This member function is overloaded and in the case of 'mapped' connections, the translator will also produce a call that requires no arguments. In that case the arguments will be set to those that were set by the connection's attributes (see Manual Connections).
Store updates issued to data objects accessed by the OpenUpdate function will not take effect until a reciprocal Close call is made.
If store buffer mode is anything other than 'CLP_STATIC', then the data object's Construct function call is required prior to data object access (see Store Records).
Updates are only allowed if they are permitted by the connection's access constraints (see Manual Connections).
All read and update accesses will block until the store has been initialized by a 'write'. Typically, stores are initialized from circuit/method initialization code during startup and prior to execution (see Circuit user functions).
Writers and updaters take precedence over readers. If a write or update request is issued to a store, and there are no free buffers then the oldest buffer (earliest written to or updated) becomes the target buffer for writes/updates. If there are no uncontended buffers and writers/updaters waiting, then subsequent read requests will block.
When writing to a data record, only the fields that are written-to will be defined. In most cases therefore, data records need to 'updated' rather than 'written'. Updating does however carry the overhead that the current data object needs to be referenced. In practice this overhead is generally small because updates to the store are broadcast to all accessing processes. This means that updates occur locally, but on 'close', the updated buffer is flushed back to the process that owns the definitive store object. On arrival, the update is broadcast to all connecting processes (except the one that initiated the update). This minimizes bandwidth for the typical case where data is 'read' many more times than it is written.